# NalogGarLoader

Утилита для импорта базы адресов ГАР в БД.

## Возможности утилиты
- Импорт из заранее скачанного архива (распакованного или нет).
- Загрузка полного архива ГАР с сайта налоговой.
- Автоматическое скачивание обновлений.

Для заливки в БД NalogGarLoader использует фреймворк **Linq2Db**, который позволяет импортировать в ГАР в [любую поддерживаемую  БД](https://linq2db.github.io/articles/general/databases.html). Для этого потребуется [соответствующий ADO драйвер](https://www.nuget.org/packages/linq2db.PostgreSQL). По умолчанию NalogGarLoader уже включает ADO драйвера Microsoft SQL Server и PostgreSQL.

Импорт в БД может работать в двух режимах: insert и update. 
Режим insert использует механизм массовых вставок (напр. Bulk Insert, group insert). Метод вставки в зависимости от типа БД [приведен здесь](https://linq2db.github.io/articles/sql/Bulk-Copy.html).
Режим update по использует конструкцию [merge into](https://linq2db.github.io/articles/sql/merge/Merge-API-Background.html).

## Конфигурация
Конфигурирование NalogGarLoader происходит в два этапа:
- Чтение настроек из json файла.
- Чтение настроек из args приложения.

Загрузка настроек происходит последовательно (сначало читаются настройки из json файла), и могут быть использованы совместно.
Все параметры доступны для указания, как в json файле, так и в параметрах комадной строки.

### Список параметров
_Параметры в **[]** не обязательные_

- **providerName "str value"** Имя провайдера. Должен быть установлен соответсвующий ADO.NET провайдер, значение дожно соответствовать [одной из констант](https://linq2db.github.io/api/linq2db/LinqToDB.ProviderName.html).

- **connectionString "str value"** Строка подключения к БД.

- **[importMode "import_mode_enum_value"]** Режим импорта. Доступные значения:
    - **manual** - (по умолчанию) импортирует в БД заранее скачанный локально ГАР, указанный в параметре source.
    - **full** - скачать последнюю версию ГАР, и импортировать ее.
    - **update** - скачать все обновления ГАР с момента последней загрузки (информация о последней загрузки берется из таблицы CurrentVersion или параметра lastImportGarVer (если указан)).

- **[insertMode "insertMode_mode_enum_value"]** Способ вставки в записей в БД. Доступные значения:
    - **update** - (по умолчанию) вставка новых и обновление существующих записей.
    - **insert** - только вставка записей (bulk insert).

- **[cleanupMode "cleanupMode_mode_enum_value"]** Очистка таблиц перед импортом. Доступные методы очистки:
    - **none** - (по умолчанию) Не выполнять очистку.
    - **delete** - Будет использоваться запроос delete from table.
    - **truncate** - Будет использоваться запроос truncate table. Убедитесь, что БД поддерживает конструкцию.
    - **dropTable** - Таблица будет удалена, и создана заново.

- **[source "str value"]** Директория с распакованным ГАР, или путь к скачанному архиву ГАР. Обязательно для ImportMode = Manual, для остальных игнорируется.

- **[tmpDir "str value"]** Директория для временного хранения скаченных архивов в режимах импорта ImportMode = Full, Update. Для Manual игнорируется.

- **[bulkInsertBufferSize "int value"]** Размер буфера для режима InsertMode.Insert. По умолчанию - 1000.

- **[maxdop "int value"]** Максимальное кол-во потоков для импорта xml фалов. По умолчанию - 8.

- **[lastImportGarVer "date_yyyyMMdd_value"]** Задает дату последней импортированной версии ГАР.
    - В режиме Manual игнорируется.
    - В режиме импорта Full будет скачана ближайшая полная выгрузка после этой даты.
    - В режиме импорта Update будут скачаны все инкреметные выгрузки от заданной до текущей даты (иначе будет взята дата из БД).

- **[includeGarTypes "GarType(1),GarType(2),...,GarType(N)]** Импортировать только указанные типы.

- **[excludeGarTypes "GarType(1),GarType(2),...,GarType(N)]** Игнорировать при импорте указанные типы.

- **[excludeStates "StateId(1),StateId(2),...,StateId(N)]** Импортировать только указанные регионы.

- **[excludeGarTypes "StateId(1),StateId(2),...,StateId(N)]** Игнорировать при импорте указанные регионы.

- **[initDbOnly]** Только инициализировать структуру БД, и выполнить очистку (если указан параметр cleanupMode).


## JSON конфигурация
Файл дожен называться NalogGarLoader.json, и распологаться в той же директории, что и NalogGarLoader.exe.
Для парараметров, которые поддерживают несколько значений (напр includeGarTypes), значение задается ввиде массива.

### Пример json файла конфигурации со всеми параметрами (при импорте используйте только нужные)
```
{
  "ImportMode": "full",
  "InsertMode": "insert",
  "CleanupMode": "truncate",
  "BulkInsertBufferSize": 1000,
  "TmpDir": "C:\\Temp\\GAR",
  "Source": "C:\\Temp\\gar_xml.zip",
  "ProviderName": "SqlServer",
  "ConnectionString": "Server=localhost;Database=GAR;Trusted_Connection=True;TrustServerCertificate=True;APP=NalogGarLoader;",
  "IncludeGarTypes": [
    "AS_NORMATIVE_DOCS_TYPES",
    "AS_APARTMENTS",
    "AS_ADDR_OBJ_TYPES",
    "AS_ADM_HIERARCHY",
    "AS_STEADS_PARAMS",
    "AS_REESTR_OBJECTS",
    "AS_APARTMENTS_PARAMS",
    "AS_ROOMS_PARAMS",
    "AS_NORMATIVE_DOCS_KINDS",
    "AS_ROOMS",
    "AS_ADDHOUSE_TYPES",
    "AS_ADDR_OBJ",
    "AS_PARAM_TYPES",
    "AS_HOUSE_TYPES",
    "AS_STEADS",
    "AS_MUN_HIERARCHY",
    "AS_APARTMENT_TYPES",
    "AS_ROOM_TYPES",
    "AS_HOUSES_PARAMS",
    "AS_ADDR_OBJ_PARAMS",
    "AS_ADDR_OBJ_DIVISION",
    "AS_OBJECT_LEVELS",
    "AS_OPERATION_TYPES",
    "AS_HOUSES"
  ],
  "ExcludeGarTypes": [
    "AS_NORMATIVE_DOCS",
    "AS_CHANGE_HISTORY",
    "AS_CARPLACES_PARAMS",
    "AS_CARPLACES"
  ],
  "IncludeStates": [
    "01",
    "02",
    "03",
    "47",
    "77",
    "78"
  ],
  "ExcludeStates": [
    "99"
  ],
  "LastImportGarVer": "20231217",
  "MaxDop": 8,
  "InitDbOnly": false
}
```

## Конфигурация через передачу параметров из командной строки
Для вывода справки из командной строки используется команда --help (-h):
NalogGarLoader.exe -h
Шаблон для передачи параметра: -параметр значение.
Для парараметров, которые поддерживают несколько значений (напр includeGarTypes), значение задается через запятую без проблела.

### Пример запуска со всеми параметрами из командной строки (используйте только нужные):
```
NalogGarLoader.exe -importmode update -insertmode update -cleanupmode delete -bulkinsertbuffersize 1000 -maxdop 8 -tmpdir "C:\Temp\GAR" -source "C:\Temp\gar_xml" -includegartypes "AS_APARTMENTS,AS_HOUSES,AS_ROOMS,AS_ADDR_OBJ,AS_MUN_HIERARCHY" -excludegartypes "AS_NORMATIVE_DOCS,AS_CHANGE_HISTORY" -includestates "01,02,03" -excludestates "04,05,06" -providername SqlServer -connectionstring "Server=localhost;Database=GAR;Trusted_Connection=True;TrustServerCertificate=True;APP=NalogGarLoader;" -lastimportgarver "20231101" -initdbonly
```